TNotes.typescript

Appearance

0078. tsconfig.json 快速入门

0078. tsconfig.json 快速入门 ​

1. 🎯 本节内容 ​

  • tsconfig.json 的作用
  • 基本配置项说明
  • 常见场景配置模板
  • 配置调试技巧
  • 最佳实践建议

2. 🫧 评价 ​

tsconfig.json 是 TypeScript 项目的配置文件，它决定了编译器的行为、类型检查的严格程度以及输出文件的结构。虽然 TypeScript 可以在没有配置文件的情况下工作，但在实际项目中，合理的 tsconfig.json 配置是必不可少的。

该配置文件的复杂度在于：它有 100+ 个配置选项，每个选项都会影响编译行为。新手常见的问题是：

  1. 不知道哪些选项是必需的
  2. 不理解选项之间的依赖关系
  3. 照搬网上的配置导致问题

本节将从实用角度出发，介绍最常用的配置选项，并提供不同场景的配置模板。掌握这些内容后，你就能根据项目需求定制合适的 TypeScript 简单配置了。

3. 🤔 什么是 tsconfig.json？ ​

tsconfig.json 是 TypeScript 项目的配置文件，用于指定：

配置类别用途示例选项
编译选项控制编译器行为target, module, strict
文件包含/排除指定哪些文件需要编译include, exclude, files
路径映射配置模块解析paths, baseUrl
类型检查控制类型检查严格度strictNullChecks, noImplicitAny
输出配置控制编译产物outDir, declaration
txt
有 tsconfig.json：
  tsc                # 按配置文件编译项目
  tsc --watch        # 监听模式

没有 tsconfig.json：
  tsc file.ts        # 只能编译单个文件
  tsc file.ts --target ES2020  # 需要手动指定所有选项

4. 🤔 如何创建 tsconfig.json？ ​

4.1. 方法 1：使用命令 tsc --init 自动生成 ​

bash
# 生成默认配置
tsc --init

下面是目前 25.11 生成的 tsconfig.json 示例：

json
{
  // Visit https://aka.ms/tsconfig to read more about this file
  "compilerOptions": {
    // File Layout
    // "rootDir": "./src",
    // "outDir": "./dist",

    // Environment Settings
    // See also https://aka.ms/tsconfig/module
    "module": "nodenext",
    "target": "esnext",
    "types": [],
    // For nodejs:
    // "lib": ["esnext"],
    // "types": ["node"],
    // and npm install -D @types/node

    // Other Outputs
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,

    // Stricter Typechecking Options
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,

    // Style Options
    // "noImplicitReturns": true,
    // "noImplicitOverride": true,
    // "noUnusedLocals": true,
    // "noUnusedParameters": true,
    // "noFallthroughCasesInSwitch": true,
    // "noPropertyAccessFromIndexSignature": true,

    // Recommended Options
    "strict": true,
    "jsx": "react-jsx",
    "verbatimModuleSyntax": true,
    "isolatedModules": true,
    "noUncheckedSideEffectImports": true,
    "moduleDetection": "force",
    "skipLibCheck": true,
  }
}

4.2. 方法 2：继承社区模板 ​

bash
# 安装基础配置
npm install --save-dev @tsconfig/node18

# 继承配置
{
  "extends": "@tsconfig/node18/tsconfig.json",
  "compilerOptions": {
    // 自定义覆盖
  }
}

4.3. 方法 3：手动创建 tsconfig.json 文件 ​

json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true
  },
  "include": ["src//*"],
  "exclude": ["node_modules", "dist"]
}

5. 🤔 tsconfig.json 配置文件的基本结构是什么样的？ ​

json
{
  // 继承其他配置
  "extends": "./base-config.json",

  // 编译选项
  "compilerOptions": {
    /* 基础选项 */
    "target": "ES2020", // 目标 JS 版本
    "module": "ESNext", // 模块系统
    "lib": ["ES2020", "DOM"], // 包含的类型库
    // ...

    /* 严格检查 */
    "strict": true, // 开启所有严格检查
    // ...

    /* 模块解析 */
    "moduleResolution": "node", // 模块解析策略
    "baseUrl": "./", // 基础路径
    "paths": {
      // 路径映射
      "@/*": ["src/*"]
    },
    // ...

    /* 输出 */
    "outDir": "./dist", // 输出目录
    "declaration": true, // 生成 .d.ts
    "sourceMap": true // 生成 source map
    // ...
  },

  // 包含的文件
  "include": ["src//*"],

  // 排除的文件
  "exclude": ["node_modules", "dist"],

  // 精确指定文件（不常用）
  "files": ["src/main.ts"]
}
json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src"]
}

6. 🤔 常用编译选项有哪些？ ​

6.1. 必知选项（按重要性排序） ​

选项作用推荐值说明
strict开启所有严格检查true包含若干个子选项
target编译目标ES2020根据运行环境选择
module模块系统ESNext现代项目用 ESNext
lib包含的类型库["ES2020", "DOM"]浏览器项目需要 DOM
outDir输出目录"./dist"编译产物位置
rootDir源码根目录"./src"保持目录结构
moduleResolution模块解析策略"node"Node.js 风格解析
esModuleInteropESM/CJS 互操作true兼容默认导入
skipLibCheck跳过库文件检查true加快编译速度

6.2. strict 包含的选项 ​

json
{
  "compilerOptions": {
    "strict": true
    // 等价于：
    // "noImplicitAny": true,           // 禁止隐式 any
    // "strictNullChecks": true,        // 严格 null 检查
    // "strictFunctionTypes": true,     // 严格函数类型
    // "strictBindCallApply": true,     // 严格 bind/call/apply
    // "strictPropertyInitialization": true,  // 类属性必须初始化
    // "noImplicitThis": true,          // 禁止隐式 this
    // "alwaysStrict": true             // 生成 "use strict"
  }
}

6.3. 不同开发场景下的一些常见配置示例 ​

json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "jsx": "react-jsx", // React 17+ 新 JSX 转换
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true
  }
}
json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs", // Node.js 使用 CJS
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
    "types": ["node"] // 包含 Node.js 类型
  }
}
json
{
  "compilerOptions": {
    "target": "ES2015", // 兼容性考虑
    "module": "ESNext",
    "declaration": true, // 生成 .d.ts
    "declarationMap": true, // 生成 .d.ts.map
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "skipLibCheck": true
  }
}

7. 🤔 如何调试 tsconfig.json 配置？ ​

7.1. 查看实际生效的配置 ​

bash
# 查看编译器使用的配置
tsc --showConfig

# 输出示例：
{
  "compilerOptions": {
    "target": "es2020",
    "module": "esnext",
    "strict": true,
    ...
  },
  "files": [],
  "include": ["src//*"],
  "exclude": ["node_modules", "dist"]
}

7.2. 检查哪些文件会被编译 ​

bash
# 列出所有会被编译的文件
tsc --listFiles

# 输出示例：
/path/to/project/src/index.ts
/path/to/project/src/utils.ts
/path/to/project/node_modules/typescript/lib/lib.es2020.d.ts
...

7.3. 查看模块解析过程 ​

bash
# 查看模块如何被解析
tsc --traceResolution

# 输出示例：
======== Resolving module 'lodash' from '/path/to/project/src/index.ts'. ========
Module resolution kind is not specified, using 'NodeJs'.
Loading module 'lodash' from 'node_modules' folder, target file type 'TypeScript'.
File '/path/to/project/node_modules/lodash.ts' does not exist.
File '/path/to/project/node_modules/lodash.tsx' does not exist.
...

7.4. 常见问题排查 ​

bash
# 检查 include/exclude 配置
tsc --listFiles | grep "your-file.ts"

# 解决方案：
# 1. 确认文件路径在 include 中
# 2. 确认文件未在 exclude 中
bash
# 检查模块解析
tsc --traceResolution > resolution.log

# 解决方案：
# 1. 检查 moduleResolution 设置
# 2. 检查 paths 配置
# 3. 检查 baseUrl 设置
bash
# 逐步开启严格检查
{
  "strict": false,
  "noImplicitAny": true,        // 先开启这个
  "strictNullChecks": false     // 逐步开启其他
}

7.5. 配置验证工具 ​

json
// 使用 JSON Schema 验证
{
  "$schema": "https://json.schemastore.org/tsconfig",
  "compilerOptions": {
    // VS Code 会提供自动补全和错误检查
  }
}

8. 🔗 引用 ​

Discussions